The objective of this chapter’s tutorial is to explore the design and development of methods. Methods are the process side of Prograph. The essential power of Prograph comes from its marriage of the dataflow model of process description with the conceptual clarity and flexibility of class-based object orientation.
In the previous tutorial, you developed knowledge and skills in creating structure within a Prograph environment to implement an application design. The goal of this tutorial is for you to learn how to make the objects you can now create behave any way you wish. To that end, you explore method*714* case structure, including the use of multicase local methods as a means of conditional execution of subtasks. List, loop, and mixed multiplexes, both on method and primitive operations, are also covered.
Prograph has an enormously rich set of control and multiplex annotations. This tutorial presents only a subset of these features and demonstrates their capabilities. Some additional annotations find their way into other tutorial exercises. But exploring some of these features is left up to you.
The Reference*935* manual provides information on all the capabilities of Prograph. As you begin to tackle your own applications, if you think Prograph should be able to do something, it probably can. Check the Reference manual and look at the many example files for solutions beyond those presented here.
t Method Cases for Conditional Execution
*188*The most basic Prograph method is one that simply “does its thing” when called, always doing the same thing under any and all circumstances. Many of the methods you have developed so far have been of this simple type. But circumstances often require varying responses to varying conditions.
Most programming languages provide a means of*354* conditional execution. Prograph is no exception. In text-based languages, a particular syntax is used to structure such variations in program flow. Typical grammatical constructions for conditional execution are:*429**430**1160*
IF <condition> THEN <response> END
or
IF <condition> THEN <trueResponse> ELSE <falseResponse> END
or
WHILE <condition> DO <this> END
or*147*
CASE <selectorLabel> OF
<label1> : <response1> ;
<label2> : <response2> ;
<label3> : <response3> ;
END
While an initial comparison would suggest that Prograph’s*139* case structure most closely resembles the case statement above, Prograph actually combines the functionality of all these forms in its case structure, control annotations, and*563* *790**797*Match operation features. As you become increasingly familiar with the various combinations of Prograph conditional controls, you could reasonably conclude that Prograph provides among the most complete and flexible conditional-execution models implemented in a programming language to date.
*756*The most basic Prograph conditional execution form is the*213* Next Case annotation*590* with a*651* Match operation or a conditional test based on one or more of the available boolean primitives. Next Case annotation has two forms.*753* Next Case on Failure:
 
and*755* Next Case on Success:
 
The*200* control annotations are the small square boxes to the right of the Match operations which are looking for an input string, "Grapefruit", to decide whether to complete the case or proceed to the next case.
The Next Case on Failure annotation has an 5 in the Next Case box.
 
Attached to a boolean operation, a*754* Next Case on Failure means, “If this test fails, go to the next case.” Attached to a Match operation, a Next Case on Failure means, “If the value coming into this Match operation is not equal to the constant value of this operation, go to the next case.”
The Next Case on Success annotation has a 3 in the Next Case box.
 
Attached to a boolean operation, a Next Case on Success means, “If this test succeeds, go to the next case.” Attached to a*564* *652*Match operation, a Next Case on Success means, “If the value coming into this Match operation is equal to the constant value of this operation, go to the next case.”
In the simplest form, a method using Next Case and having two cases is like an IF <matchTest> THEN <case1> ELSE <case2> expression. The most concise <matchTest> form is one using the*798* Match operation.
The Match operation is a shorthand notation equivalent to an expression using the boolean primitive*834* = *7*with the Match value’s constant as the right input to the = primitive:
 
is equivalent to
 
In either form above, if the input value is equal to ten, the test succeeds and execution of the method continues in the current case. If the input value is anything other than ten, the test fails and Prograph immediately stops execution of the current case and begins executing the next case.
When more than two cases are involved, the equivalent grammatical construction is similar to an IF…THEN…ELSEIF…ELSEIF…ELSE…END or to a CASE OF…END expression in text-based programming languages.
Let’s now explore multiple cases. Develop a method which, given a month name as input, tells how many days are in the month—a Prograph implementation of “30 days has September, April, June and November; all the rest have 31, except for February, which has 28.” (Forget about leap years for the time being.)
u Start Prograph and create a universal method, month query, to feed the user’s response into a days in month method as follows:
 
u Double-click the left side of the days in month operation to create the new universal method and open its first case window. This conditional execution decision tests whether the input month name is found in the list of month names for months with 30 days. Construct your first case of days in month to look like this:
 
The conditional test is a Next Case on Success. The (in) operation returns zero if it does not find the required input item in the left input list (here, if the month name is not in the 30 days list). So, a Next Case on Success test signals a drop to the next case when it succeeds in not finding a value.
u Option-click the right*127* case arrow in the title bar of the days in month method to simultaneously create and open a second case of this method. As a reminder, these are your*133* case controls:
 
u Taking your design cues from the reminder rhyme, “All the rest have 31…,” make case two jump to its conclusion without a conditional test.
 
Of course this neglects the condition in the rhyme’s third line with regard to February. Though the rhyme’s conditional ordering serves well as a mnemonic device, it is a bad model for direct computer implementation. Case two implements the gross assumption “all the rest have 31” unconditionally, so adding the “except February” clause as case three is nonproductive. Case three never executes.
Your implementation, then, must put the February-exception case ahead of the “31-days-assumption” case. Prograph’s *145*Case List pane makes this kind of case modification easy.
u Click the Case List button to open the Case List pane along the bottom of the days in month 2:2 window. Position the crosshair cursor between the first and second case icons in the*130* Case List pane and Command-click to create a new case.
 
The title of the active case window has changed to days in month 3:3, indicating the case has been “bumped down the line” by your creation of a new second case.
u Double-click the second case icon in the Case List pane to open its case window. Use a Match operation with a February string constant to check for the except-February condition.
 
Note that here the test is a Next Case on Failure as the Match is looking for a particular string and fails if it does not find it.
u Command-click the close box to collectively close all three cases of days in month. Open the Stack window and execute month query several times. Enter a different month name each time you execute the query and observe the case executions in the Stack window. (Use some Step/Show or Breakpoint settings to get a better look at how days in month cases are executed.)
Observing the executions of the cases of days in month in the Stack window and reflecting on the configuration of the current implementation, two things become clear.
o Of the 12 possible answers, 7 are responded to by the third case, making for an inefficient conditional decision process.
o Non-month name inputs are responded to as having 31 days.
Let’s add a design enhancement to address these weaknesses as follows:
u Open days in month and open its Case List pane. To make the third case the first, simply drag the third icon in the Case List pane to the left and release the mouse button when the ghost rectangle you are dragging is over or slightly to the left of the first case icon. This case shuffle is reflected in the title bar of the window, which shows that what was the first case, 1:3, has become the second case, 2:3.
u Double-click the first case icon and edit its case. Provide a conditional test to check for the input name in the list of the seven month names for months having 31 days. (You can use a cut, paste, and edit of the conditional test operations from the second case to make quick work of this modification.)
 
u Add a fourth case that passes the string "Sorry, this is not a month name. Try again." to the output bar to provide an error-catching condition for unrecognized input.
Now rerun month query a few times with the Stack window open and notice the difference. Nearly 60 percent of the acceptable month names are responded to by the first case. Typos and other entry errors get a reasonable response.
The overall design of cases for days in month has been improved. The flexible editing features of the*146**131* Case List pane let you develop and modify a method’s case structure quickly and easily. In addition to the click to create and drag to reorder features, you can cut, copy, paste, and replicate cases in the Case List pane. And any of these actions can be performed on multiply selected icons within the Case List pane.
In addition to direct icon manipulations in the Case List pane, a number of keyboard-plus-case-arrow click routines provide shortcuts for creating, opening and closing cases within a method. Refer to the Reference *936* manual for additional information on the Option-click, Shift-click, and Command-click features of the case arrows. (Or simply experiment here with days in month to determine how these keyboard modifiers affect clicks on the case arrows.)
t Local Methods for Design Organization
*256**530*Local methods serve a variety of purposes. Perhaps the most basic is design organization and “housecleaning.” A complex method can suffer a condition called “datalink spaghetti.” *1091*As a method becomes more complex, it can become increasingly difficult to determine what the method is doing and what connections datalinks are making. Local methods*532* can solve this problem by providing logical organization and clearing out the datalink confusion.
There is a chicken-and-egg aspect to local methods. You can work top-down, laying in your high-level local operation nodes in a case window, or you can use the*655* Opers to Local*801**809* facility to encapsulate a collection of logically related operations within a method‚Äôs case that is growing too complex. Reconsider the Folks Database example you developed in the Grand Tour. You can find a nonlocalized version of this mini-application in your Tutorial Examples Δí .
u Save your current work to disk so you can return to it after this example. Then open the Spaghetti Folks DB file in the Ch 7 Δí folder.
u Open and inspect the Person/Add method:
 
As you can see, the nonlocalized version of Add is getting out of hand: you have to scroll vertically or significantly enlarge its window to see every operation that takes place when a Person is added to the People database. There is little room for explanatory comments. And the relationship of the operations to each other is lost in the*257* crisscrossing paths of datalinks.
Such complex methods are difficult to maintain, as you can quickly forget what is flowing where, even after only a few days away from working on your application. The task can be even worse if someone other than the original author is attempting to maintain or extend this application.
You can clean up this method and provide logical order to it by refreshing your skills in using the Opers to Local feature of the Prograph editor. The higher-level tasks that this collection of operations performs are:
o make a new Person
o add Person to database
o update the window.
By nesting the operations performing each of these tasks into a local, what is going on in your code becomes obvious to anyone who inspects your application.
u Start by isolating the operations that create the new Person object whose name is entered in the Folks Database window. Drag a selection rectangle enclosing the operations in the top half of the case window. Your collection of selected operations should look like this before you capture them in a local.
 
u Select Opers to Local from the Opers menu. Type make a new Person as the name of the newly created local operation. Next drag a selection rectangle around the two People persistents and the attach-r operation, and then select Opers to Local. Type add Person to database to name this local.
 
u Capture the remaining operations in a local and type update the window to name it. Drag the locals around to get a clean and organized appearance. This once unwieldy collection of operations is now represented by this high-level case diagram.
NOTE: Depending on the exact arrangement of the operations that you “capture” in a local as above, you may occasionally get some crisscrossing in your datalinks. This is due to the topographical algorithm that computes the necessary roots and terminals for the local and makes all the right connections to the new local’s encapsulated operations.
Once you have captured and cleaned up your top-level case diagram, you may occasionally want to manually override the editor’s connections. In the above example, your update the window local may have resulted in a crossed input to the left and right terminals. For the clean appearance as shown above, you can simply rewire the datalinks. All links to the left can be switched to the right and those on the right can go to the left, for example.
Such rearrangement is a matter of taste and situation. If you are the sole author of an application, it might not matter if occasional crossed datalinks occur. If you are a member of a team, on a large-scale corporate project for example, you might want to clean up parts of your case diagrams to improve their appearance when they are printed out for documentation purposes. Also, cleaner diagrams can be more easily maintained by others over time.
The important point is that the Prograph editor does a correct job for you automatically with regard to capturing operations into local methods. Your aesthetics and sensibilities may, however, be more critical than its algorithms.
The transformed method is now more self-documenting. It is apparent that three tasks are performed when the Add button is pushed. Further, the data and object-flow dependencies among the subtasks have become obvious. Compare the insights you can gain from inspecting this case diagram from the original nonlocalized version. Clearly, local methods can contribute much to logically organizing your methods.
